Exact Synergy Enterprise

 

How-to: Synergy webservice and Azure AD - Connecting to a Synergy webservice using Microsoft Azure Active Directory

Note:

• This document is only relevant to the controlled release participants.
• This is not available for Exact Cloud customers.
  

Introduction

This document describes how to connect to the Exact Synergy Enterprise web services using the Microsoft Azure Active Directory for authentication. This document makes use of the OAuth protocol (SAML is not covered in this document, but works in a similar way). Together with this document, you will find an example in SoapUI.

Note:

• This document is not a tutorial on how to set up Exact Synergy Enterprise and Azure AD.
• This document is not a detailed explanation of the authentication protocols used by Azure AD.

Prerequisites

For the examples in this document, you will need the following:

• An Microsoft Azure account,
• a configured Azure Active Directory,
• Synergy Enterprise, configured using Azure AD with OAuth,
• credentials of a Synergy user and administrator access to the Azure AD, and
• SoapUI.

Authentication process

Traditionally, Exact Synergy Enterprise supports Windows authentication (NTLM credentials) and Basic authentication (username and password). Recently, Exact Synergy Enterprise also supports Azure Active Directory (WAAD) in combination with the SAML or OAuth protocol.

For detailed information about the OAuth protocol used by Azure AD, see https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-app-types.

Authentication process flow in a browser

When you log in to Exact Synergy Enterprise in a browser, you get redirected to an Azure AD login page. On this page, you enter your credentials (username and password) and after a successful authentication, you will be redirected back to Exact Synergy Enterprise. 

Please note that this is an interactive authentication flow, and as such, the user must key in their credentials manually.

Authentication process flow in an App

When using an App, you have a similar flow as a browser. 

Please note that this is also an interactive authentication flow.

Authentication process flow for a server process

When you want to call the Exact Synergy Enterprise web services from a server process, you cannot use one of the authentication flows described above. You will need an authentication flow that does not require any user interaction. For this you can use the “resource owner password credential grant” flow.

This flow uses a combination of username, password, and client secret to get authentication. This flow does not use any user interaction, because only the owner of the Azure Active Directory can provide the client secret. The rest of the document will explain how to use this flow to successfully call an Exact Synergy Enterprise web service.

Note: Please be aware that the client secret must be kept secret for everyone. It is not something that should be shared with users or other parties.

Example

The call to an Exact Synergy Enterprise web service requires two steps:

1. Retrieve an Azure Active Directory access token using OAuth.
2. Call the Exact Synergy Enterprise web service and provide the access token.

Retrieve an access token

To retrieve an access token, you need the following information:

• The Azure AD endpoints.
• Username and password of an Exact Synergy Enterprise user in the Azure AD.
• The client ID of the Exact Synergy Enterprise instance in the Azure AD.
• The client secret of the Exact Synergy Enterprise instance in the Azure AD.

Endpoints

You can find the endpoints by clicking Endpoints in the Azure portal, via Default Directory ➔ App registrations.

Username and password

You can find the users via Default Directory ➔ Users - All users.

Client ID

The client ID uniquely identifies your application. You can find those at Default Directory ➔ App registrations. For Exact Synergy Enterprise, you have configured two App registrations:

1. Web Registration
2. Public Registration

You will need the client ID from the web registration:

Client secret

Note: Be aware that the client secret must remain SECRET – never provide it to others!

The client secret can be found via the web application registration at Default Directory ➔ App registrations XXXXXXXXX_ESE_WEB ➔ Certificates & secrets.

Please note that when you create a client secret, the complete secret is displayed to you. You must write this down because you will not be able to retrieve it at a later moment.

Get the token

With all information above, you can retrieve the token by sending a POST message to the OAuth 2.0 token endpoint (v1). In the message content, you need to provide the client ID, client secret, username, and password. Please be aware that the values must be URL encoded.

client_id=58xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx81
&resource=58xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx81
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&username=WAAD@xxxxxxxxxxxxxxxx.onmicrosoft.com
&password=xxxxxxxxxxxxxxxx
&client_secret=1xx%1Cxxx%9AxxxxxxxxxxxxxxxxxxxxxxxxxxxxxU
&grant_type=password

The content-type header must be set to application/x-www-form-urlencoded.

This call returns a JSON message with the access token

{
      "token_type": "Bearer",
      "scope": "User.Read",
      "expires_in": "3600",
      "ext_expires_in": "3600",
      "expires_on": "1567169792",
      "not_before": "1567165892",
      "resource": "58xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx81",
      "access_token": "eyJ0...
                                                      ...QIA",
      "refresh_token": "AQAB...
                                                       ...IAA"
}

This access token will be used to authenticate with the Exact Synergy Enterprise web service (see next section).

Call a webservice

With the access token you have retrieved from the token endpoint of the Azure AD, you can now call an Exact Synergy Enterprise web service. In the example, we will retrieve a call to the Account web services.

Instead of providing the NTLM credentials, you now need to provide the Azure AD access token. This is done via two HTTP headers:

1. AccessTokenType
2. AccessToken

AccessTokenType must be set to OAUTH and AccessToken must contain your access token. Please be aware that you should not provide any other authentication or authorization.

GET http://localhost/ese/services/Exact.entity.REST.svc/Account?%24top=10 HTTP/1.1
Accept-Encoding: gzip,deflate
Accept: application/json,text/javascript; charset=utf-8
AccessToken: eyJ0 ... QIA
AccessTokenType: OAUTH
Content-Type: application/json
Host: localhost
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

SoapUI

For the complete SoapUI example, see this file WAAD-soapui-project.xml.

     

Main Category:	Attachments & notes	Document Type:	Online help main
Category:		Security  level:	All - 0
Sub category:		Document ID:	29.165.364
Assortment:	Exact Synergy Enterprise	Date:	20-03-2020
Release:		Attachment:
Disclaimer